home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Ulog.man < prev    next >
Encoding:
Text File  |  1989-01-03  |  8.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Ulog                  C Library Procedures                   Ulog
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Ulog - obtain or update information in the database of  user
  12.      logins and logouts.
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee  <<uulloogg..hh>>
  16.  
  17.      Ulog_Data *
  18.      UUlloogg__LLaassttLLooggiinn(_u_i_d)
  19.  
  20.      int
  21.      UUlloogg__GGeettAAllllLLooggiinnss(_n_u_m_E_n_t_r_i_e_s, _l_o_c_P_t_r, _d_a_t_a_A_r_r_a_y)
  22.  
  23.      int
  24.      UUlloogg__RReeccoorrddLLooggiinn(_u_i_d, _l_o_c_a_t_i_o_n, _p_o_r_t_I_D)
  25.  
  26.      int
  27.      UUlloogg__RReeccoorrddLLooggoouutt(_u_i_d, _p_o_r_t_I_D)
  28.  
  29.      int
  30.      UUlloogg__CClleeaarrLLooggiinnss()
  31.  
  32.  
  33. AARRGGUUMMEENNTTSS
  34.      int         _u_i_d           (in)      A  numerical  identifier
  35.                                          for  a  user for whom to
  36.                                          retrieve    or    update
  37.                                          information.
  38.  
  39.      int         _n_u_m_E_n_t_r_i_e_s    (in)      The number of  Ulog_Data
  40.                                          structures  contained in
  41.                                          _d_a_t_a_A_r_r_a_y.
  42.  
  43.      int         *_l_o_c_P_t_r       (in/out)  A pointer to an  integer
  44.                                          specifying  the index of
  45.                                          the next record  in  the
  46.                                          user log to access.
  47.  
  48.      Ulog_Data   _d_a_t_a_A_r_r_a_y[]   (out)     A   buffer    to    hold
  49.                                          Ulog_Data        entries
  50.                                          returned     by      the
  51.                                          Ulog_GetAllLogins   rou-
  52.                                          tine.
  53.  
  54.      char        *_l_o_c_a_t_i_o_n     (in)      String specifying  loca-
  55.                                          tion  of user logging in
  56.                                          (i.e., remote host)
  57.  
  58.      int         _p_o_r_t_I_D        (in)      Numerical identifier for
  59.                                          login port.
  60.  
  61.  
  62.  
  63. Sprite v.1.0        Printed:  January 3, 1989                   1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Ulog                  C Library Procedures                   Ulog
  71.  
  72.  
  73.  
  74. _________________________________________________________________
  75.  
  76. DDEESSCCRRIIPPTTIIOONN
  77.      The ulog library provides a facility to  record  logins  and
  78.      logouts  in  the  system,  to retrieve information about the
  79.      last time a user logged in or about all  users  logged  into
  80.      the system, and to clear the login entries for a host.  Each
  81.      host has a fixed number of entries allocated to  it  in  the
  82.      user  log  database  file.   One  entry,  with  a  _p_o_r_t_I_D of
  83.      UULLOOGG__LLOOCC__CCOONNSSOOLLEE, is reserved for the  console  of  a  host;
  84.      there  are  (UULLOOGG__MMAAXX__PPOORRTTSS - 1) other entries available for
  85.      rlogin processes.  (There is currently no facility for  mul-
  86.      tiple local logins, such as over a serial line.)
  87.  
  88.      The _u_l_o_g library converts between the  ASCII  representation
  89.      stored in the database and an internal C structure, known as
  90.      a Ulog_Data structure.  This structure contains  information
  91.      giving <uid,hostID,portID> corresponding to a user logged in
  92.      on a particular ``port'' on a particular host.   Each  login
  93.      entry  also  includes  the  time  of the login, which is the
  94.      ttvv__sseecc part of a ttiimmee structure.  It also includes any addi-
  95.      tional  information for the location of the user; this is an
  96.      arbitrary string that typically gives the host from which an
  97.      rlogin  occurs.  Two database files are used: one for logins
  98.      on a host/port basis, and one for the  last  login  by  each
  99.      user.
  100.  
  101.      A Ulog_Data structure is defined as follows:
  102.  
  103.           ttyyppeeddeeff ssttrruucctt {
  104.               iinntt _u_i_d;              /* user identifier */
  105.               iinntt _h_o_s_t_I_D;           /* host for which data is
  106.                                        valid */
  107.               iinntt _p_o_r_t_I_D;           /* port within host */
  108.               iinntt _u_p_d_a_t_e_d;          /* login time (in seconds since
  109.                                        1/1/70); 0 if invalid */
  110.               cchhaarr _l_o_c_a_t_i_o_n[UULLOOGG__LLOOCC__LLEENNGGTTHH];
  111.                                     /* location of user */
  112.           } Ulog_Data;
  113.  
  114.      The  UUlloogg__LLaassttLLooggiinn(())  procedure  returns  a  pointer  to  a
  115.      statically-allocated  Ulog_Data  structure.   Therefore, the
  116.      contents of the structure may change on subsequent calls  to
  117.      UUlloogg__LLaassttLLooggiinn(()).      The     information    returned    by
  118.      UUlloogg__LLaassttLLooggiinn(()) corresponds to the most recent login by the
  119.      user specified by _u_i_d.
  120.  
  121.      UUlloogg__GGeettAAllllLLooggiinnss(()) provides a mechanism for retrieving mul-
  122.      tiple  login  entries  at  once.   The user must allocate an
  123.      array of Ulog_Data structures, and  pass  the  size  of  the
  124.      array    and    a    pointer   to   it   as   arguments   to
  125.      UUlloogg__GGeettAAllllLLooggiinnss(()).   In  addition,  the  _l_o_c_P_t_r   argument
  126.  
  127.  
  128.  
  129. Sprite v.1.0        Printed:  January 3, 1989                   2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Ulog                  C Library Procedures                   Ulog
  137.  
  138.  
  139.  
  140.      specifies  where  in  the  login  database to start looking.
  141.      *_l_o_c_P_t_r should be initialized to 0 prior to the  first  call
  142.      to  UUlloogg__GGeettAAllllLLooggiinnss(()).   UUlloogg__GGeettAAllllLLooggiinnss(())  returns  the
  143.      number of entries in _d_a_t_a_A_r_r_a_y that were  filled.   If  that
  144.      number  is  less than the maximum number specified by _n_u_m_E_n_-
  145.      _t_r_i_e_s, then all data has been returned.  If it is  equal  to
  146.      _n_u_m_E_n_t_r_i_e_s,  then UUlloogg__GGeettAAllllLLooggiinnss(()) should be called again
  147.      to retrieve additional entries from  the point at which  the
  148.      last call left off (given by *_l_o_c_P_t_r).
  149.  
  150.      UUlloogg__RReeccoorrddLLooggiinn(()) allows the caller to register information
  151.      for  a  new  login.  The caller specifies the user ID, loca-
  152.      tion, and port  of  the  user  logging  in.   The  procedure
  153.      obtains the hostID and current time, and records the login.
  154.  
  155.      UUlloogg__RReeccoorrddLLooggoouutt(()) provides a similar  facility  to  record
  156.      logouts.  It takes a user ID and port number, and it removes
  157.      the corresponding loginn from the list of active logins.
  158.  
  159.      UUlloogg__CClleeaarrLLooggiinnss(()) may be used at boot time to clear any old
  160.      entries  in  the  user log for the current host.  Note: if a
  161.      host is down, it may still have entries in the user log.  It
  162.      is  the  responsibility  of  the  user  to use the migration
  163.      information database to determine if a host is up, in  order
  164.      to validate user log entries.
  165.  
  166. DDIIAAGGNNOOSSTTIICCSS
  167.      UUlloogg__RReeccoorrddLLooggiinn(()),         UUlloogg__RReeccoorrddLLooggoouutt(()),         and
  168.      UUlloogg__CClleeaarrLLooggiinnss(())  return zero if all went well.  Otherwise
  169.      they return -1 and the _e_r_r_n_o  variable  contains  additional
  170.      information  about what error occurred.  UUlloogg__GGeettAAllllLLooggiinnss(())
  171.      similarly returns -1 on error, but it returns 0 if  no  more
  172.      records  are  available.   UUlloogg__LLaassttLLooggiinn(())  returns NULL on
  173.      error.
  174.  
  175. FFIILLEESS
  176.      /sprite/admin/data/userLog
  177.           The database of current logins on each host.
  178.  
  179.      /sprite/admin/data/lastLog
  180.           The database of each user's most recent login.
  181.  
  182. KKEEYYWWOORRDDSS
  183.      user log, user ID, sprite ID
  184.  
  185. SSEEEE AALLSSOO
  186.      db, mig, Mig_GetInfo, login, rlogin, rlogind
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v.1.0        Printed:  January 3, 1989                   3
  196.  
  197.  
  198.  
  199.